= The Saboteur's Cookbook

a guide to running Sabotage for the experienced user.


== Installing the system

see the wiki page "boostrap to hd image" or utils/write-hd-image.sh

== Butch, the build manager

  butch is a 700 LOC C program written from scratch, which handles the package download,
  checksum comparison, build process, and dependencies in a relatively sane manner.

  it suports the following commands

    butch install <(meta)package> <(meta)package> <(meta)package> ...
    butch rebuild <(meta)package> <(meta)package> <(meta)package> ...
    butch prefetch <(meta)package> <(meta)package> <(meta)package> ...

  currently butch will start up to 16 download threads and up to 2 build threads.
  since busybox' wget (used inside the chroot) has a number of issues, 
  it is advised to download all packages at once before starting the build process.

  this can be achieved by issuing

    butch prefetch stage0 stage1 pkg xorg gdb

  the file in which butch keeps track of what is installed is /src/pkg/installed.dat
  with the default template, butch will use /opt/packagename as DESTDIR for installs.
  the contents of that dir will then be symlinked into / in a stow-ish manner.

  use "butch unlink" command to remove symlinks to a specific package.
  use "butch relink" command to create symlinks for a pkg which is unlinked.

== Bootstrapping the system

see README.

== first steps

* keyboard layout
for the linux console:
execute "loadkeys" command, and follow the instructions.

for X:
edit /etc/xinitrc (or copy it to ~/.xinitrc and edit that one)
there's a commented line suggesting how to change setxkbmap invokation.
uncomment and change the 2-letter country code to your country.

starting X:
- be sure to edit /bin/X and enable qemu or vbox settings, 
  otherwise your controls won't work!
- execute "startx"

getting a dhcp ip address:
- execute "dhclient eth0"

setting a static ip address:
- ifconfig eth0 192.168.0.2 netmask 255.255.255.0
- route add default gw 192.168.0.1
  you can put that into a script which is automatically started from /etc/rc.local

start sshd
- sv u sshd

== System Administration

Sabotage does things a bit differently than your usual Linux
distribution!

=== The file system

Sabotage does not follow FHS.  /usr is a legacy symlink to /, /sbin is
a legacy symlink to /bin.  Software should be installed with
--prefix=/.  The times of a seperate root partition are long over.

packages are installed into /opt/$packagename and symlinked to /.

/src is where software gets built in and packages are searched for. 
/src/pkg	: package recipes, used by butch
/src/KEEP	: patches and other additional files referenced from pkg scripts
/src/tarballs	: upstream tarballs for software releases.
/src/logs	: logfiles from builds
/src/build	: directory to build packages in.
                  can grow quite big so it may be emptied from time to time...
/src/filelists	: one filelist per package, used by some butch commands.

/src is not required for sabotage to operate correctly once it has been set up,
as long as you don't want to use the build manager on that install.

if you run your sabotage system, you may want to clone the upstream
repo into /src/sabotage and create symlinks to KEEP and pkg in the git repo.

    git clone git://github.com/sabotage-linux/sabotage /src/sabotage
    rm -rf /src/pkg /src/KEEP
    ln -sf /src/sabotage/pkg /src/pkg
    ln -sf /src/sabotage/KEEP /src/KEEP

that way you can issue a git pull in /src/sabotage to update,
and have your pkg and KEEP directories always pointing to the latest version.

Everything below /local is yours, use it wisely.  Software not
packaged by Sabotage should not touch stuff outside, it could possibly
break on updates.

Use /srv/$SERVICE/$VHOST for all server data.

=== The init system

Sabotage uses runit as init system (not entirely, so far we use
Busybox init to start runsvdir).  This is cool, see
http://busybox.net/~vda/init_vs_runsv.html.

The base system has a few services, which you find in /var/service
(note that these are symlinks to /etc/service):

  dmesg - logs kernel messages
  sshd  - opensshd, down by default
  tty2, tty3, tty4 - three gettys
  crond - cron daemon

You can start services with "sv u $SERVICE" or take them down with "sv
d $SERVICE".  By default, all services in /var/service start at boot
time, unless they have a "down" file in their directory---then you'll
have to start them manually.  If you don't want to use a service at all,
best remove the symlink to /etc/service.

You can find out whats running and what is not with

  # sv s /var/service/*

Look into the service directories to find out how to add your own
services---note that you must tell them not to daemonize!

For the rest of runit, I'll refer you to the documentation at
http://smarden.org/runit/index.html

=== Logging

There is no syslog support so far, services should use "svlogd" (see
runit docs) to log into directories below /var/log.
You can inspect the logs by looking at /var/log/$SERVICE/current,
Kernel messages are found in /var/log/dmesg/current.

You can quickly look at all logs with

  # sort /var/log/*/current  |less

